﻿@page "/docs/components/file"

<Seo Canonical="/docs/components/file" Title="Blazorise FileEdit component" Description="Learn to use and work with the Blazorise FileEdit component, a customized, cross-browser consistent, file input control that supports single file and multiple files upload." />

<DocsPageTitle Path="Components/File Edit">
    Blazorise FileEdit component
</DocsPageTitle>

<DocsPageLead>
    The <Code>FileEdit</Code> component is a specialized input that provides a clean interface for selecting files.
</DocsPageLead>

<DocsPageParagraph>
    Customized, cross-browser consistent, file input control that supports single file and multiple files upload.
</DocsPageParagraph>

<DocsPageSubtitle>
    Examples
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="Single file (default)">
        On single file mode, when file is selected or user does not cancel Browse dialog, <Code>Changed</Code> event will be raised.
        The return value will be a <Code>FileChangedEventArgs</Code> that will contain only one item in the <Code>Files</Code> property.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <SingleFileEditExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="SingleFileEditExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Multiple files">
        Multiple file uploading is supported by enabling <Code>Multiple</Code> attribute to component. In this case <Code>Files</Code> property
        of <Code>FileChangedEventArgs</Code> can contain multiple files.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <MultipleFileEditExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="MultipleFileEditExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Directories">
        Directory uploading is supported by enabling <Code>Directory</Code> attribute to component. In this case <Code>Files</Code> property
        of <Code>FileChangedEventArgs</Code> can contain multiple files within a directory.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <DirectoryFileEditExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="DirectoryFileEditExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Multiple Directories">
        Multiple Directory uploading is supported by enabling <Code>Directory</Code> and <Code>Multiple</Code> attribute to component. In this case <Code>Files</Code> property
        of <Code>FileChangedEventArgs</Code> can contain multiple files within a directory.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <MultipleDirectoryFileEditExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="MultipleDirectoryFileEditExample" />
</DocsPageSection>


<DocsPageSection>
    <DocsPageSectionHeader Title="Limiting to certain file types">
        You can limit the file types by setting the <Code>Filter</Code> attribute to a string containing the allowed file type(s).
        To specify more than one type, separate the values with a comma.
        <br />
        <br />
        To accept any file type, leave <Code>Filter</Code> as null (default).
        <br />
        <br />
        <Alert Color="Color.Info" Visible>
            <AlertDescription>
                <Strong>Note:</Strong> Not all browsers support or respect the <Code>accept</Code> attribute on file inputs.
            </AlertDescription>
        </Alert>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <ExtensionsLimitFileEditExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="ExtensionsLimitFileEditExample" />
</DocsPageSection>

<DocsPageSubtitle>
    Events
</DocsPageSubtitle>

<DocsPageParagraph Title="Changed">
    This is the main event that will be called every time a user selects a single or multiple files.
    Depending on the mode in which the <Code>FileEdit</Code> currently operates. In all cases the event argument is the same.
    Only difference is that <Code>Files</Code> array will contain single or multiple items.
</DocsPageParagraph>

<DocsPageParagraph Title="Written">
    This event will be called on every buffer of data that has being written to the destination stream.
    It is directly related to the <Code>MaxMessageSize</Code> attribute found on <Code>FileEdit</Code> component and will contain the information
    about currently processed file, it’s offset and data array.
</DocsPageParagraph>

<DocsPageParagraph Title="Progressed">
    Similar to the <Code>Written</Code>, this event will also be called while file is writing to the destination stream but it will
    contain only the progress and percentage on how much the file is being uploaded.

    <Alert Color="Color.Info" Visible>
        <AlertDescription>
            <Strong>Note:</Strong> If <Code>Progressed</Code>  and <Code>Written</Code> events aren't important to you, we highly advise you the usage of the <Code>DisableProgressReport</Code> Parameter, as it will improve file transfer significantly.
        </AlertDescription>
    </Alert>
</DocsPageParagraph>

<DocsPageParagraph Title="Started">
    This event will be called each time one of the selected file(s) has started the upload process.
</DocsPageParagraph>

<DocsPageParagraph Title="Ended">
    This event is fired after the file has ended the upload process. If there was no error it will have <Code>Success</Code> property set to true.
</DocsPageParagraph>

<DocsPageSubtitle>
    Examples
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="WriteToStreamAsync">
        In this example you can see the usage of all events, including the <Code>Written</Code> and <Code>Progressed</Code>.
        For your own use case you can just focus on <Code>Changed</Code> event.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <WriteToStreamFileEditExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="WriteToStreamFileEditExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="OpenReadStream">
        Using <Code>OpenReadStream</Code> on the file you can process the file as it is streamed from the browser to your code,
        this is mirrors the API found in <Blazorise.Link To="https://docs.microsoft.com/en-us/aspnet/core/blazor/file-uploads" Target="Target.Blank">ASP.NET Core Input File component</Blazorise.Link>, for example

        <Alert Color="Color.Info" Visible>
            <AlertDescription>
                <Strong>Note:</Strong> We highly advise the usage of this api on Blazor WebAssembly as it is very performant.
            </AlertDescription>
        </Alert>

    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <WriteToStreamFileEditExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="OpenReadStreamFileEditExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Reset">
        By default after each file upload has finished, file input will automatically reset to it’s initial state.
        If you want this behavior disabled and control it manually you need to first set <Code>AutoReset</Code> to <Code>false</Code>.
        After that you can call <Code>Reset()</Code> every time you want the file input to be reset.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <ResetFileEditExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="ResetFileEditExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Show Picker">
        <Paragraph>
            If you want to show the <Anchor To="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/showPicker">default picker</Anchor> that comes with the file input element you can make it by using the <Code>ShowPicker()</Code> function.
        </Paragraph>
        <Paragraph>
            <Strong TextColor="TextColor.Info">Note:</Strong> Keep in mind that not all browser will support the <Code>ShowPicker()</Code> function.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <FileEditShowPickerExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="FileEditShowPickerExample" />
</DocsPageSection>

<DocsPageSubtitle>
    Functions
</DocsPageSubtitle>

<Table>
    <TableHeader ThemeContrast="ThemeContrast.Light">
        <TableRow>
            <TableHeaderCell>Name</TableHeaderCell>
            <TableHeaderCell>Description</TableHeaderCell>
        </TableRow>
    </TableHeader>
    <TableBody>
        <TableRow>
            <TableRowCell><Code>ShowPicker()</Code></TableRowCell>
            <TableRowCell>Show a browser picker for the file input.</TableRowCell>
        </TableRow>
    </TableBody>
</Table>

<DocsPageSubtitle>
    API
</DocsPageSubtitle>

<Heading Size="HeadingSize.Is3">
    Attributes
</Heading>

<DocsAttributes>
    <DocsAttributesItem Name="ChildContent" Type="RenderFragment">
        Input content.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Feedback" Type="RenderFragment">
        Placeholder for validation messages.
    </DocsAttributesItem>
    <DocsAttributesItem Name="AutoReset" Type="bool" Default="true">
        If true file input will be automatically reset after it has being uploaded.
    </DocsAttributesItem>
    <DocsAttributesItem Name="BrowseButtonLocalizer" Type="TextLocalizerHandler" Default="null">
        Function used to handle browse button localization that will override a default <Code>ITextLocalizer</Code>.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Changed" Type="@("EventCallback<FileChangedEventArgs>")">
        Occurs every time the file(s) has changed.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Ended" Type="@("EventCallback<FileEndedEventArgs>")">
        Occurs when an individual file upload has ended.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Filter" Type="string" Default="null">
        Types of files that the input accepts.
    </DocsAttributesItem>
    <DocsAttributesItem Name="MaxChunkSize" Type="int" Default="20480">
        Max chunk size (in bytes) when uploading the file.
    </DocsAttributesItem>
    <DocsAttributesItem Name="SegmentFetchTimeout" Type="TimeSpan" Default="TimeSpan.FromMinutes(1)">
        Gets or sets the Segment Fetch Timeout when uploading the file.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Multiple" Type="bool" Default="false">
        Specifies that multiple files can be selected.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Directory" Type="bool" Default="false">
        Specifies that directories can be selected.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Placeholder" Type="string" Default="null">
        Sets the placeholder for the empty file input.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Progressed" Type="@("EventCallback<FileProgressedEventArgs>")">
        Notifies the progress of file being uploaded.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Started" Type="@("EventCallback<FileStartedEventArgs>")">
        Occurs when an individual file upload has started.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Written" Type="@("EventCallback<FileWrittenEventArgs>")">
        Occurs every time the part of file has being uploaded.
    </DocsAttributesItem>
    <DocsAttributesItem Name="MaxFileSize" Type="long" Default="long.MaxValue">
        Maximum file size in bytes, checked before starting upload (note: never trust client, always check file size at server-side). Defaults to long.MaxValue.
    </DocsAttributesItem>
    <DocsAttributesItem Name="DisableProgressReport" Type="bool" Default="false">
        Gets or sets whether report progress should be disabled. By enabling this setting, Progressed and Written callbacks won't be called. Internal file progress won't be tracked.
        This setting can speed up file transfer considerably.
    </DocsAttributesItem>
    <DocsAttributesItem Name="ReadOnly" Type="bool" Default="false">
        Add the readonly boolean attribute on an input to prevent modification of the input’s value.
    </DocsAttributesItem>
    <DocsAttributesItem Name="Disabled" Type="bool" Default="false">
        Add the disabled boolean attribute on an input to prevent user interactions and make it appear lighter.
    </DocsAttributesItem>
</DocsAttributes>